home *** CD-ROM | disk | FTP | other *** search
/ Aminet 12 / Aminet 12 (1996)(GTI - Schatztruhe)[!][Jun 1996].iso / Aminet / dev / misc / ctimer.lha / ctimer_dir / include / ctimer.h
Encoding:
C/C++ Source or Header  |  1992-09-02  |  10.7 KB  |  374 lines
  1. /*
  2.     ·C·O·D·E·X· ·D·E·S·I·G·N· ·S·O·F·T·W·A·R·E·
  3.     presents:
  4.  
  5.     ctimer.o V1.00 (simple timer routine)
  6.     TABLEN = 3 !
  7.  
  8.     This is a really simple method of beeing able to
  9.     wait() for a time being flown.
  10.  
  11.     Descriptions follow below. Note that all times won't
  12.     be very exact.
  13.     This object had been designed to have some _simple_
  14.     and _easy_ to use routines, not powerful high end
  15.     timers !
  16.  
  17.     (c)April 1996 by Hans Bühler / codex@studi.mathematik.hu-berlin.de
  18.                                              Kirchstr.22 * 10557 Berlin 21 * Ger
  19. */
  20.  
  21. #ifndef    _CTIMER_H
  22.  
  23. #define    _CTIMER_H    1
  24.  
  25. #include    <exec/types.h>
  26. #include    <exec/memory.h>
  27. #include    <exec/ports.h>
  28. #include    <exec/lists.h>
  29. #include    <exec/nodes.h>
  30. #include    <dos/dos.h>
  31.  
  32. // --------------------------
  33. // defines
  34. // --------------------------
  35.  
  36. /*
  37.     general constants
  38.     -----------------
  39. */
  40.  
  41. #define    CTIM_MAX_TIME            0x7FFFFFFF            // no longer waiting
  42. #define    CTIM_MAX_DELAY            0xFF                    // maximum 1/50s time units
  43. #define    CIIM_DEFDELAY            0x0A                    // recommended 'timeDelay' for ctimerInit()
  44.  
  45. /*
  46.     return codes
  47.     ------------
  48. */
  49.  
  50. // general
  51. #define    TRET_OKAY                0x00                    // everything went well
  52. #define    TRET_OUTOFMEMORY        0x01                    // :-(
  53. #define    TRET_BADINPUT            0x02                    // you did something wronh
  54. #define    TRET_BADTIMER            0x03                    // "timername" timer doesn't exist
  55.  
  56. // ctimerInit()
  57. #define    TRET_BADNAME            0x10                    // timer with that name already found !
  58. #define    TRET_NOSIGNAL            0x11                    // can't allocate new (temp) signal for calling process
  59. #define    TRET_NOPROCESS            0x12                    // can't launch child process
  60. #define    TRET_NOCHILDCONFIG    0x13                    // failed to initialize new process
  61.  
  62. // ctimerRem()
  63. #define    TRET_BADTASK            0x22                    // ctimerRem() _must_ be called by the same task
  64.                                                                 // which called ctimerInit()
  65.  
  66. // very bad errors
  67. #define    TRET_BADCASE_1            0xF0                    // illegal job ID
  68.  
  69. // ----------------------------------
  70. // YOU have to make these available
  71. // ----------------------------------
  72.  
  73. /*
  74.     extern struct DOSBase            *DOSBase;
  75.     extern struct ExecBase            *SysBase;
  76. */
  77.  
  78. // ----------------------------------
  79. // functions1: setup & remove a timer
  80. // ----------------------------------
  81.  
  82. /*
  83.     Before you can use some of the lower timed functions,
  84.     you have to initialize a timer using ctimerInit().
  85.     A timer which has been initialized must be removed
  86.     by ctimerRem() later called by the _same_ task
  87.     which had called ctimerInit(). This is because
  88.     allowing another task would neccessarily force you
  89.     to check whether ctimerRem() failed (I need a signal
  90.     to be free) and that could cause trouble, anyhow.
  91.     However, timer functions can be used from every task.
  92.  
  93.     In all routines, a timer will be identified by a
  94.     string (like "my_prog_timer").
  95. */
  96.  
  97. extern __asm UBYTE ctimerInit(    register __a0 char *timername,
  98.                                             register __d0 BYTE pri,
  99.                                             register __d1 UBYTE delaySteps);
  100.  
  101. /*
  102.     ctimerInit()
  103.     ------------
  104.  
  105.     J:    Setup a new timer process.
  106.  
  107.     I:    timername    -    ID name of timer. If left zero, TRET_BADINPUT will be
  108.                             returned.
  109.         pri            -    Priority of timer process. I guess, 1 is a good choice.
  110.         delaySteps    -    Every "timed" function expects a ULONG value indicating
  111.                             how many of "delaySteps" 1/50s it shall wait.
  112.                             Note that the timer process will do the following
  113.                             (if a job is sent to it; otherwise it will Wait(), of
  114.                             course):
  115.  
  116.                                 while(!quit)
  117.                                 {
  118.                                     if(job_to_check)
  119.                                     {
  120.                                         Delay(delaySteps);            // dos/Delay()
  121.  
  122.                                         checkJobs();
  123.                                     }
  124.                                     else
  125.                                         Wait(until_Job_comes_or_Quit);
  126.                                 }
  127.  
  128.                             I recommend a value of CTIM_DEFDELAY (10) or something.
  129.                             TRET_BADINPUT will be returned if 0 is found.
  130.  
  131.     O:    TRET_OKAY                everything went all right ;-)
  132.         TRET_BADINPUT            (see above)
  133.         TRET_BADNAME            there's already a timer with the name "timername"
  134.         TRET_OUTOFMEMORY        just guess
  135.         TRET_NOSIGNAL            AllocSignal(-1) call failed
  136.         TRET_NOPROCESS            CreateNewProc() failed
  137.         TRET_NOCHILDCONFIG    failed to initialize child (AllocSignal(-1) failed)
  138.  
  139.     See also:    exec/InitSemaphore(), exec/AddSemaphore(), exec/AllocSignal(),
  140.                     exec/AllocVec(),  dos/CreateNewProc(), ctimer/ctimerRem()
  141. */
  142.  
  143. extern __asm UBYTE ctimerRem(register __a0 char *timername);
  144.  
  145. /*
  146.     ctimerRem()
  147.     -----------
  148.  
  149.     J:    Removes a previously ctimerInit()ialized timer.
  150.         Note that only the _same_ task that called ctimerInit() is allowed
  151.         to call that function (returns TRET_BADTASK otherwise).
  152.  
  153.     I:    timername    -    name of timer.
  154.  
  155.     O:    TRET_OKAY        allright.
  156.         TRET_BADTIMER    can't find timer "timername"
  157.         TRET_BADTASK    (see above)
  158.  
  159.     See also:    ctimer/ctimerInit()
  160. */
  161.  
  162. extern __asm UBYTE ctimerCancelAll(register __a2 char *timername,
  163.                                               register __d2 BOOL execute);
  164.  
  165. /*
  166.     ctimerCancelAll()
  167.     -----------------
  168.  
  169.     J:    Cancels all jobs currently set to the timer.
  170.  
  171.     I:    timername    -    name of timer
  172.         execute        -    execute jobs when removing or not
  173.                             (see ctimerCancelSignal() and ctimerCancelPutMsg())
  174.  
  175.     O:    TRET_OKAY        allright
  176.         TRET_BADTIMER    can't find timer "timername"
  177.  
  178.     See also:    ctimer/ctimerCancelSignal()
  179.                     ctimer/ctimerCancelPutMsg()
  180. */
  181.  
  182. // ----------------------------------
  183. // functions2: timed events
  184. // ----------------------------------
  185.  
  186. extern __asm UBYTE ctimerSignal(    register __a0 struct Task *task,
  187.                                             register __d0 ULONG signals,
  188.                                             register __a2 char *timername,
  189.                                             register __d2 ULONG time);
  190.  
  191. extern __asm LONG ctimerCancelSignal(register __a0 struct Task *task,
  192.                                             register __d0 ULONG signals,
  193.                                             register __a2 char *timername,
  194.                                             register __d2 BOOL set);
  195.  
  196. /*
  197.     ctimerSignal()
  198.     --------------
  199.  
  200.     J:    exec/Signal() with a timer delay.
  201.         When the "time" passed by Signal(task,signals) will be executed.
  202.         You can invoke/break this operation by using ctimerCancelSignal().
  203.  
  204.     I:    task            -    Task to signal. If left zero, the task having called
  205.                             ctimerSignal() will be signalled.
  206.         signals        -    Signalmask to set. 0 will end in TRET_BADINPUT.
  207.         timername    -    Name of timer.
  208.         time            -    Time to wait in "delaySteps" (see ctimerInit()) units.
  209.                             0 will return TRET_BADINPUT.
  210.  
  211.     O:    TRET_OKAY            okay, job started.
  212.         TRET_BADINPUT        (see above)
  213.         TRET_BADTIMER        timer "timername" unknown.
  214.         TRET_OUTOFMEMORY    ;-)
  215.  
  216.     See also: exec/Signal(), exec/Wait(), ctimer/ctimerCancelSignal()
  217.  
  218.  
  219.  
  220.     ctimerCancelSignal()
  221.     --------------------
  222.  
  223.     J:    Break a ctimerSignal() job.
  224.         If the reasons why you wanted to delayed execute Signal() had
  225.         changed,  you can remove the job from the timer using this operation.
  226.  
  227.     I:    task,signals,timername    -    MUST BE same as used when calling
  228.                                             ctimerSignal()
  229.         set                            -    TRUE if you want to execute
  230.                                             exec/Signal(task,signals), however
  231.                                             (will only be done if the job is been
  232.                                             found in the timer's job list.
  233.                                             that means that if the job has been
  234.                                             done while you were doing other things
  235.                                             the signal is set for sure (-1 returned
  236.                                             in that case)).
  237.  
  238.     O:    >=0:    job removed; time that already passed by.
  239.         -1:    job not found (see notes above).
  240.         -2:    "timername" time not found.
  241.  
  242.     See also:    ctimer/ctimerSignal()
  243. */
  244.  
  245. extern __asm UBYTE ctimerPutMsg(    register __a0 struct MsgPort *port,
  246.                                             register __a1 struct Message *msg,
  247.                                             register __a2 char *timername,
  248.                                             register __d2 ULONG time);
  249.  
  250. extern __asm LONG ctimerCancelPutMsg(register __a0 struct MsgPort *port,
  251.                                             register __a1 struct Message *msg,
  252.                                             register __a2 char *timername,
  253.                                             register __d2 BOOL send);
  254.  
  255. /*
  256.     ctimerPutMsg()
  257.     --------------
  258.  
  259.     J:    exec/PutMsg() with a timer delay.
  260.         When the "time" passed by PutMsg(port,msg) will be executed.
  261.         You can invoke/break this operation by using ctimerCancelPutMsg().
  262.  
  263.         Do not make assumptions about further services from ctimerPutMsg().
  264.         The port and msg parameter are taken as pointers and nothing
  265.         else than PutMsg() will be done with them.
  266.         You have to free the memory for the msg by yourself etc !
  267.  
  268.     I:    port            -    port to put msg to (0 => TRET_BADINPUT).
  269.         msg            -    msg to put to port. 0 will end in TRET_BADINPUT.
  270.         timername    -    Name of timer.
  271.         time            -    Time to wait in "delaySteps" (see ctimerInit()) units.
  272.                             0 will return TRET_BADINPUT.
  273.  
  274.     O:    TRET_OKAY            okay, job started.
  275.         TRET_BADINPUT        (see above)
  276.         TRET_BADTIMER        timer "timername" unknown.
  277.         TRET_OUTOFMEMORY    ;-)
  278.  
  279.     See also: exec/PutMsg(), exec/GetMsg(), exec/WaitPort(), ctimer/ctimerCancelPutMsg()
  280.  
  281.  
  282.  
  283.     ctimerCancelPutMsg()
  284.     -------------------
  285.  
  286.     J:    Break a ctimerPutMsg() job.
  287.         If the reasons why you wanted to delayed execute PutMsg() had
  288.         changed,  you can remove the job from the timer using this operation.
  289.  
  290.     I:    port,msg,timername    -    MUST BE same as used when calling
  291.                                         ctimerPutMsg()
  292.         send                        -    TRUE if you want to execute
  293.                                         exec/PutMsg(port,msg), however
  294.                                         (will only be done if the job is been
  295.                                         found in the timer's job list.
  296.                                         that means that if the job has been
  297.                                         done while you were doing other things
  298.                                         the msg is send for sure (-1 returned
  299.                                         in that case)).
  300.  
  301.     O:    >=0:    job removed; time that already passed by.
  302.         -1:    job not found (see notes above).
  303.         -2:    "timername" time not found.
  304.  
  305.     See also:    ctimer/ctimerPutMsg()
  306. */
  307.  
  308. extern __asm LONG ctimerWait(    register __d0 ULONG *breakMask,
  309.                                         register __a2 char *timername,
  310.                                         register __d2 ULONG time);
  311.  
  312. /*
  313.     ctimerWait()
  314.     ------------
  315.  
  316.     J:    This is a very simple routine which allows you to wait until
  317.         the "time" passed by or any of the signals in "*breakMask"
  318.         are received.
  319.         This is a very nice function to implement abortable jobs.
  320.  
  321.     I:    breakMask    -    Ptr to ULONG.
  322.                             ctimerWait() will read the "breakMask" from
  323.                             that LONG. If one of these signals will be received,
  324.                             ctimerWait() aborts waiting.
  325.                             When returning (without error), the *breakMask
  326.                             will represent the signals that have been
  327.                             received by Wait().
  328.                             Only signals you requested will be shown.
  329.         timername    -    Name of timer.
  330.         time            -    Time to wait in "delaySteps" (see ctimerInit()) units.
  331.                             0 will return -1.
  332.  
  333.     O:    >0    :    Time that passed by. If >0 (and 0, possibly), check
  334.                 the contence of *breakMask where the signals that have
  335.                 been received are stored in.
  336.         0    :    Time passed by completely (_no_ breakMask signal received).
  337.         -1    :    Error (bad timer, bad time (=0), no free signal, etc).
  338.  
  339.     Example:
  340.  
  341.         You want to wait "time" time units but want to abort if CTRl-C or
  342.         CTRL-D is been pressed (assuming there's a timer called
  343.         "my_timer"):
  344.  
  345.         returns    0    :    time passed by
  346.                     1    :    ctrl-c
  347.                     2    :    ctrl-d
  348.                     -1    :    failure
  349.  
  350.         UBYTE WaitCtrlC(ULONG time)
  351.         {
  352.             LONG        sigs,i;
  353.  
  354.             sigs    =    SIGBREAKF_CTRL_C | SIGBREAKF_CTRL_D;    // dos/dos.h
  355.  
  356.             i = ctimerWait(&sigs,"my_timer",time);
  357.  
  358.             if(i < 0)
  359.                 return -1;
  360.  
  361.             if(sigs & SIGBREAKF_CTRL_C)
  362.                 return 1;
  363.             if(sigs & SIGBREAKF_CTRL_D)
  364.                 return 2;
  365.  
  366.             return 0;
  367.         }
  368.  
  369.     See also:    ctimer/ctimerSignal(), ctimer/ctimerCancelSignal(),
  370.                     exec/Wait(), exec/AllocSignal()
  371. */
  372.  
  373. #endif
  374.